Amiga Developer CD 2.1

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Contributions / Nordic_Global / Networking / MiamiSDK / doc / Socket.doc < prev next >

Wrap

Text File | 1997-12-26 | 72.7 KB | 2,402 lines

TABLE OF CONTENTS bsdsocket.library/accept bsdsocket.library/bind bsdsocket.library/CloseSocket bsdsocket.library/connect bsdsocket.library/Dup2Socket bsdsocket.library/Errno bsdsocket.library/getdtablesize bsdsocket.library/gethostbyaddr bsdsocket.library/gethostbyname bsdsocket.library/gethostid bsdsocket.library/gethostname bsdsocket.library/getnetbyaddr bsdsocket.library/getnetbyname bsdsocket.library/getpeername bsdsocket.library/getprotobyname bsdsocket.library/getprotobynumber bsdsocket.library/getservbyname bsdsocket.library/getservbyport bsdsocket.library/GetSocketEvents bsdsocket.library/getsockname bsdsocket.library/getsockopt bsdsocket.library/inet_addr bsdsocket.library/inet_lnaof bsdsocket.library/Inet_LnaOf bsdsocket.library/inet_makeaddr bsdsocket.library/Inet_MakeAddr bsdsocket.library/inet_netof bsdsocket.library/Inet_NetOf bsdsocket.library/inet_network bsdsocket.library/inet_ntoa bsdsocket.library/Inet_NtoA bsdsocket.library/IoctlSocket bsdsocket.library/listen bsdsocket.library/ObtainSocket bsdsocket.library/recv bsdsocket.library/recvfrom bsdsocket.library/recvmsg bsdsocket.library/ReleaseCopyOfSocket bsdsocket.library/ReleaseSocket bsdsocket.library/select bsdsocket.library/send bsdsocket.library/sendmsg bsdsocket.library/sendto bsdsocket.library/SetErrnoPtr bsdsocket.library/SetSocketSignals bsdsocket.library/setsockopt bsdsocket.library/shutdown bsdsocket.library/socket bsdsocket.library/SocketBaseTagList bsdsocket.library/vsyslog bsdsocket.library/WaitSelect bsdsocket.library/accept bsdsocket.library/accept NAME accept -- accept a connection on a socket SYNOPSIS news = accept( s, addr, addrlen ); D0 D0 A0 A1 long accept( long s, struct sockaddr *addr, long *addrlen ); FUNCTION The argument s is a socket that has been created with socket(), bound to an address with bind(), and is listening for connections after a listen(). The accept() argument extracts the first connection request on the queue of pending connections, creates a new socket with the same properties of s and allocates a new file descriptor for the socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, accept() blocks the caller until a connection is present. If the socket is marked non-blocking and no pending connections are present on the queue, accept() returns an error as described below. The accepted socket may not be used to accept more connections. The original socket s remains open. The argument addr is a result parameter that is filled in with the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the domain in which the communication is occurring. The addrlen is a value-result parameter; it should initially contain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types, currently with SOCK_STREAM. It is possible to select() a socket for the purposes of doing an accept() by selecting it for read. One can obtain user connection request data without confirming the connection by issuing a recvmsg() call with an msg_iovlen of 0 and a non-zero msg_controllen, or by issuing a getsockopt() request. Similarly, one can provide user connection rejection information by issuing a sendmsg() call with providing only the control information, or by calling setsockopt(). The call returns -1 on error. If it succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. The accept() will fail if: [EBADF] The descriptor is invalid. [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM. [EWOULDBLOCK] The socket is marked non-blocking and no connections are present to be accepted. INPUTS s - socket addr - address addrlen - pointer to address length RESULT news (D0) - new socket bsdsocket.library/bind bsdsocket.library/bind NAME bind -- bind a name to a socket SYNOPSIS ret = bind( s, name, namelen ); D0 D0 A0 D1 long bind( long s, struct sockaddr *name, long namelen ); FUNCTION bind() assigns a name to an unnamed socket. When a socket is created with socket() it exists in a name space (address family) but has no name assigned. bind() requests that name be assigned to the socket. The rules used in name binding vary between communication domains. For the Internet domain (AF_INET) the name has to be passed in a "struct sockaddr_in". If the bind is successful, a 0 value is returned. A return value of -1 indicates an error, which is further specified in the return value of Errno(). The bind() call will fail if: [EBADF] s is not a valid descriptor. [EADDRNOTAVAIL] The specified address is not available from the local machine. [EADDRINUSE] The specified address is already in use. [EINVAL] The socket is already bound to an address. INPUTS s - socket name - name (address) namelen - name length RESULT ret (D0) - return value bsdsocket.library/CloseSocket bsdsocket.library/CloseSocket NAME CloseSocket -- Close a socket SYNOPSIS ret = CloseSocket( s ); D0 D0 long CloseSocket( long s ); FUNCTION The CloseSocket() call deletes a descriptor from the per-process socket reference table. If this is the last reference to the underlying object, the socket will be closed, and associated naming information and queued data are discarded. When a process exits and closes bsdsocket.library, all associated socket descriptors are freed, but since there is a limit on active descriptors per processes, the CloseSocket() function call is useful when a large quantity of socket descriptors are being handled. Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the return value of Errno() is set to indicate the error. CloseSocket() will fail if: [EBADF] s is not an active socket descriptor. INPUTS s - socket RESULT ret (D0) - return value bsdsocket.library/connect bsdsocket.library/connect NAME connect -- initiate a connection on a socket SYNOPSIS ret = connect( s, name, namelen ); D0 D0 A0 D0 long connect( long s, struct sockaddr *name, long namelen ); FUNCTION The parameter s is a socket. If it is of type SOCK_DGRAM, this call specifies the peer with which the socket is to be associated; this address is that to which datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type SOCK_STREAM, this call attempts to make a connection to another socket. The other socket is specified by name, which is an address in the communications space of the socket. Each communications space interprets the name parameter in its own way. Generally, stream sockets may successfully connect() only once; datagram sockets may use connect() multiple times to change their association. Datagram sockets may dissolve the association by connecting to an invalid address, such as a null address. If the connection or binding succeeds, 0 is returned. Otherwise a -1 is returned, and a more specific error code is stored in errno. The connect() call fails if: [EBADF] S is not a valid descriptor. [EADDRNOTAVAIL] The specified address is not available on this machine. [EAFNOSUPPORT] Addresses in the specified address family cannot be used with this socket. [EISCONN] The socket is already connected. [ETIMEDOUT] Connection establishment timed out without establishing a connection. [ECONNREFUSED] The attempt to connect was forcefully rejected. [ENETUNREACH] The network isn't reachable from this host. [EADDRINUSE] The address is already in use. [EINPROGRESS] The socket is non-blocking and the connection cannot be completed immediately. It is possible to select() for completion by selecting the socket for writing. [EALREADY] The socket is non-blocking and a previous connection attempt has not yet been completed. INPUTS s - socket name - name (address) namelen - name length RESULT ret (D0) - return value bsdsocket.library/Dup2Socket bsdsocket.library/Dup2Socket NAME Dup2Socket -- duplicate an existing socket descriptor SYNOPSIS s = Dup2Socket( olds, news ); D0 D0 D1 long Dup2Socket( long olds, long news ); FUNCTION Dup2Socket() duplicates an existing socket descriptor and returns its value to the calling process. The argument olds is a small non-negative integer index in the per-process descriptor table. The value must be less than the size of the table, which is returned by getdtablesize(). The value of the new descriptor news is specified in the call as well. If this descriptor is already in use, the descriptor is first deallocated as if a CloseSocket() call had been done first. If -1 is passed as the new descriptor then the lowest available descriptor will be used. The socket referenced by the descriptor does not distinguish between olds and news in any way. The value -1 is returned if an error occurs in either call. The return value of Errno() indicates the cause of the error. Dup2Socket() fail if: [EBADF] olds or news is not a valid active descriptor INPUTS olds - old socket descriptor news - new socket descriptor RESULT s (D0) - new allocated socket descriptor bsdsocket.library/Errno bsdsocket.library/Errno NAME Errno -- return the current error code SYNOPSIS err = Errno(); D0 long Errno (void); FUNCTION Errno() returns the value of the errno variable used in the process instance data of the protocol stack. RESULT err (D0) - current error code bsdsocket.library/getdtablesize bsdsocket.library/getdtablesize NAME getdtablesize -- get descriptor table size SYNOPSIS size = getdtablesize(); D0 long getdtablesize (void); FUNCTION Each process has a fixed size descriptor table, which is guaranteed to have at least 20 slots. The entries in the descriptor table are numbered with small integers starting at 0. The call getdtablesize() returns the size of this table. RESULT size (D0) - descriptor table size bsdsocket.library/gethostbyaddr bsdsocket.library/gethostbyaddr NAME gethostbyaddr -- get network host entry SYNOPSIS he = gethostbyaddr( addr, len, type ); D0 A0 D0 D1 struct hostent *gethostbyaddr( char *addr, long len, long type ); FUNCTION The gethostbyaddr() function returns a pointer to an object with the following structure describing an internet host referenced by name or by address, respectively. This structure contains either the information obtained from the DNS name server, or broken-out fields from a configuration entry in the local host table. struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ The members of this structure are: h_name Official name of the host. h_aliases A zero terminated array of alternate names for the host. h_addrtype The type of address being returned; currently always AF_INET. h_length The length, in bytes, of the address. h_addr_list A zero terminated array of network addresses for the host. Host addresses are returned in network byte order. h_addr The first address in h_addr_list; this is for backward compatibility. Error return status from gethostbyaddr() is indicated by return of a null pointer. The variable h_errno may then be checked to see whether this is a temporary failure or an invalid or unknown host, by calling SocketBaseTags with a code of SBTC_HERRNO. The variable h_errno can have the following values: HOST_NOT_FOUND No such host is known. TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. NO_DATA The requested name is valid but does not have an IP address; this is not a temporary error. This means that the name is known to the name server but there is no address associated with this name. Another type of request to the name server using this domain name will result in an answer; for example, a mail-forwarder may be registered for this domain. INPUTS addr - address len - address length type - address type RESULT he (D0) - host entry bsdsocket.library/gethostbyname bsdsocket.library/gethostbyname NAME gethostbyname -- get network host entry SYNOPSIS he = gethostbyname( name ); D0 A0 struct hostent *gethostbyname( char *name ); FUNCTION The gethostbyname() function returns a pointer to an object describing an internet host. Please see the description of gethostbyaddr() for more information on that structure and on possible error conditions. INPUTS name - host name RESULT he (D0) - host entry bsdsocket.library/gethostid bsdsocket.library/gethostid NAME gethostid -- get unique identifier of current host SYNOPSIS id = gethostid(); D0 long gethostid (void); FUNCTION Each Internet host is supposed to have a 32-bit identifier that is unique among all systems in existence. This is normally an IP address for the local machine. gethostid() returns the 32-bit identifier for the current machine. This function has been deprecated. DO NOT assume that the value returned by gethostid() is a valid IP address. RESULT id (D0) - hostid bsdsocket.library/gethostname bsdsocket.library/gethostname NAME gethostname -- get name of current host SYNOPSIS ret = gethostname( name, namelen ); D0 A0 D0 long gethostname( char *name, long namelen ); FUNCTION gethostname() returns the standard host name for the current machine. The parameter namelen specifies the size of the name array. The returned name is null-terminated unless insufficient space is provided. If the call succeeds a value of 0 is returned. If the call fails, a value of -1 is returned and an error code is placed in the global location errno. INPUTS name - host name buffer namelen - length of host name buffer RESULT ret (D0) - return code bsdsocket.library/getnetbyaddr bsdsocket.library/getnetbyaddr NAME getnetbyaddr -- get network entry SYNOPSIS netent = getnetbyaddr( net, type ); D0 D0 D1 struct netent *getnetbyaddr( long net, long type ); FUNCTION The getnetbyaddr() function returns a pointer to an object with the following structure containing the broken-out fields of an entry in the local network data base. struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net number type */ unsigned long n_net; /* net number */ }; The members of this structure are: n_name The official name of the network. n_aliases A zero terminated list of alternate names for the network. n_addrtype The type of the network number returned; currently only AF_INET. n_net The network number. Network numbers are returned in machine byte order. The getnetbyaddr() function sequentially searches from the beginning of the table until a matching net address and type is found, or until the end of the table is reached. Network numbers are supplied in host order. INPUTS net - network type - network type RESULT netent (D0) - network entry bsdsocket.library/getnetbyname bsdsocket.library/getnetbyname NAME getnetbyname -- get network entry SYNOPSIS netent = getnetbyname( name ); D0 A0 struct netent *getnetbyname( const unsigned char *name ); FUNCTION The getnetbyname() function returns a pointer to an object which represents a network entry in the local network data base. Please see the description of getnetbyaddr() for more information on that structure and on possible error conditions. INPUTS name - network name RESULT netent (D0) - network entry bsdsocket.library/getpeername bsdsocket.library/getpeername NAME getpeername -- get name of connected peer SYNOPSIS ret = getpeername( s, name, namelen ); D0 D0 A0 A1 long getpeername( long s, struct sockaddr *name, long *namelen ); FUNCTION getpeername() returns the name of the peer connected to socket s. The namelen parameter should be initialized to indicate the amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). The name is truncated if the buffer provided is too small. A 0 is returned if the call succeeds, -1 if it fails. The call succeeds unless: [EBADF] The argument s is not a valid descriptor. [ENOTCONN] The socket is not connected. [ENOBUFS] Insufficient resources were available in the system to perform the operation. INPUTS s - socket name - name (address) buffer namelen - size of name buffer RESULT ret (D0) - return code bsdsocket.library/getprotobyname bsdsocket.library/getprotobyname NAME getprotobyname -- get protocol entry SYNOPSIS proto = getprotobyname( name ); D0 A0 struct protoent *getprotobyname( char *name ); FUNCTION The getprotobyname() function returns a pointer to an object with the following structure containing the broken-out fields of an entry in the local network protocol data base. struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ int p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero terminated list of alternate names for the protocol. p_proto The protocol number. The getprotobyname() function sequentially searches from the beginning of the table until a matching protocol name is found, or the end of the table is reached. INPUTS name - protocol name RESULT proto (D0) - protocol entry bsdsocket.library/getprotobynumber bsdsocket.library/getprotobynumber NAME getprotobynumber -- get protocol entry SYNOPSIS proto = getprotobynumber( id ); D0 D0 struct protoent *getprotobynumber( long id ); FUNCTION The getprotobynumber() function returns a pointer to an object which represents a network protocol entry in the local network protocol data base. Please see the description of getprotobyname() for more information on that structure. INPUTS id - protocol id RESULT proto (D0) - protocol entry bsdsocket.library/getservbyname bsdsocket.library/getservbyname NAME getservbyname -- get service entry SYNOPSIS serv = getservbyname( name, proto ); D0 A0 A1 struct servent *getservbyname( char *name, char *proto ); FUNCTION The getservbyname() function returns a pointer to an object with the following structure containing the broken-out fields of an entry in the local network services data base. struct servent { char *s_name; /* official name of service */ char **s_aliases; /* alias list */ int s_port; /* port service resides at */ char *s_proto; /* protocol to use */ }; The members of this structure are: s_name The official name of the service. s_aliases A zero terminated list of alternate names for the service. s_port The port number at which the service resides. Port numbers are returned in network byte order. s_proto The name of the protocol to use when contacting the service. The getservbyname() function sequentially searches from the beginning of the table until a matching protocol name or port number is found, or until the end of the table has been reached. If a protocol name is also supplied (non-NULL), searches must also match the protocol. INPUTS name - service name proto - protocol name RESULT serv (D0) - service entry bsdsocket.library/getservbyport bsdsocket.library/getservbyport NAME getservbyport -- get service entry SYNOPSIS serv = getservbyport( port, proto ); D0 D0 A0 struct servent *getservbyport( long port, const unsigned char *proto ); FUNCTION The getservbyport() function returns a pointer to an object which represents a network service entry in the local network services data base. Please see the description of getservbyname() for more information on that structure. INPUTS port - port number proto - protocol name RESULT serv (D0) - service entry bsdsocket.library/GetSocketEvents bsdsocket.library/GetSocketEvents NAME GetSocketEvents -- get asynchronous socket events SYNOPSIS s = GetSocketEvents( eventsp ); D0 A0 long GetSocketEvents( ULONG *eventsp ); FUNCTION GetSocketEvents() returns the next asynchronous event for sockets, and removes it from the internal queue. The socket number for which the event has occured is returned. If no asynchronous event is pending then -1 is returned. Applications are notified of asynchronous events through the event signal (which has to be set earlier by calling SocketBaseTags() with code SBTC_SIGEVENTMASK). Several different events can occur for each socket. To enable reporting of specific events for a socket call getsockopt() with the option SO_EVENTMASK. After calling GetSocketEvents() the ULONG pointed to by eventsp contains the mask of all events that have occured for the returned socket. Possible events: FD_ACCEPT: A new connection is waiting to be accepted. The kernel keeps track of each pending connection. If more than one connection is pending then the kernel immediately generates a new FD_ACCEPT event until all pending connections are accounted for. FD_CLOSE: The connection was closed. If it was closed due to an error then the FD_ERROR event is set as well. FD_CONNECT: A pending connection has been established. This event is an indication that a non-blocking connect() has been completed. FD_ERROR: An asynchronous error has occured. FD_OOB: New out-of-band data is available for reading. FD_READ: New data is available for reading. FD_WRITE: The socket is able to accept data for writing again without blocking (only for non-blocking sockets). INPUTS eventsp - pointer to event mask RESULT s (D0) - socket bsdsocket.library/getsockname bsdsocket.library/getsockname NAME getsockname -- get socket name SYNOPSIS ret = getsockname( s, name, namelen ); D0 D0 A0 A1 long getsockname( long s, struct sockaddr *name, long *namelen ); FUNCTION getsockname() returns the current name for the specified socket. The namelen parameter should be initialized to indicate the amount of space pointed to by name. On return it contains the actual size of the name returned (in bytes). A 0 is returned if the call succeeds, -1 if it fails. The call succeeds unless: [EBADF] The argument s is not a valid descriptor. [ENOBUFS] Insufficient resources were available in the system to perform the operation. INPUTS s - socket name - name (address) buffer namelen - size of name buffer RESULT ret (D0) - return code bsdsocket.library/getsockopt bsdsocket.library/getsockopt NAME getsockopt -- get options on sockets SYNOPSIS ret = getsockopt( s, level, optname, optval, optlen ); D0 D0 D1 D2 A0 A1 long getsockopt( long s, long level, long optname, void *optval, long *optlen ); FUNCTION getsockopt() returns the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost ``socket'' level. When manipulating socket options the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, level is specified as SOL_SOCKET. To manipulate options at any other level the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, level should be set to the protocol number of TCP; see getprotoent(). The parameters optval and optlen are used to access option values for setsockopt(). For getsockopt() they identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt(), optlen is a value-result parameter, initially containing the size of the buffer pointed to by optval, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, optval may be NULL. Optname and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file <sys/socket.h> contains definitions for socket level options, described below. Options at other protocol levels vary in format and name. Most socket-level options utilize a long parameter for optval. For setsockopt(), the parameter should be non-zero to enable a boolean option, or zero if the option is to be disabled. SO_LINGER uses a struct linger parameter, defined in <sys/socket.h>, which specifies the desired state of the option and the linger interval (see below). SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval parameter, defined in <sys/time.h>. The following options are recognized at the socket level. Except as noted, each may be examined with getsockopt() and set with setsockopt(). SO_DEBUG enables recording of debugging information (not functional in all protocol stacks) SO_REUSEADDR enables local address reuse SO_REUSEPORT enables duplicate address and port bindings SO_KEEPALIVE enables keep connections alive SO_DONTROUTE enables routing bypass for outgoing messages SO_LINGER linger on close if data present SO_BROADCAST enables permission to transmit broadcast messages SO_OOBINLINE enables reception of out-of-band data in band SO_SNDBUF set buffer size for output SO_RCVBUF set buffer size for input SO_RCVBUF set buffer size for input SO_SNDLOWAT set minimum count for output SO_RCVLOWAT set minimum count for input SO_SNDTIMEO set timeout value for output SO_RCVTIMEO set timeout value for input SO_TYPE get the type of the socket (get only) SO_ERROR get and clear error on the socket (get only) SO_EVENTMASK set the event mask for asynchronous notification SO_DEBUG enables debugging in the underlying protocol modules. SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind() call should allow reuse of local addresses. SO_REUSEPORT allows completely duplicate bindings by multiple processes if they all set SO_REUSEPORT before binding the port. This option permits multiple instances of a program to each receive UDP/IP multicast or broadcast datagrams destined for the bound port. SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket receive an error indication when attempting to send data. SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address. SO_LINGER controls the action taken when unsent messages are queued on socket and a close() is performed. If the socket promises reliable delivery of data and SO_LINGER is set, the system will block the process on the close attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a timeout period, termed the linger interval, is specified in seconds in the setsockopt() call when SO_LINGER is requested). If SO_LINGER is disabled and a close is issued, the system will process the close in a manner that allows the process to continue as quickly as possible. The option SO_BROADCAST requests permission to send broadcast datagrams on the socket. With protocols that support out-of-band data, the SO_OOBINLINE option requests that out-of-band data be placed in the normal data input queue as received; it will then be accessible with recv calls without the MSG_OOB flag. Some protocols always behave as if this option is set. SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer sizes allocated for output and input buffers, respectively. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values. SO_SNDLOWAT is an option to set the minimum count for output operations. Most output operations process all of the data supplied by the call, delivering data to the protocol for transmission and blocking as necessary for flow control. Nonblocking output operations will process as much data as permitted subject to flow control without blocking, but will process no data if flow control does not allow the smaller of the low water mark value or the entire request to be processed. A select() operation testing the ability to write to a socket will return true only if the low water mark amount could be processed. The default value for SO_SNDLOWAT is set to a convenient size for network efficiency, often 1024. SO_RCVLOWAT is an option to set the minimum count for input operations. In general, receive calls will block until any (non-zero) amount of data is received, then return with the smaller of the amount available or the amount requested. The default value for SO_RCVLOWAT is 1. If SO_RCVLOWAT is set to a larger value, blocking receive calls normally wait until they have received the smaller of the low water mark value or the requested amount. Receive calls may still return less than the low water mark if an error occurs, a signal is caught, or the type of data next in the receive queue is different than that returned. SO_SNDTIMEO is an option to set a timeout value for output operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for output operations to complete. If a send operation has blocked for this much time, it returns with a partial count or with the error EWOULDBLOCK if no data were sent. In the current implementation, this timer is restarted each time additional data are delivered to the protocol, implying that the limit applies to output portions ranging in size from the low water mark to the high water mark for output. SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a struct timeval parameter with the number of seconds and microseconds used to limit waits for input operations to complete. In the current implementation, this timer is restarted each time additional data are received by the protocol, and thus the limit is in effect an inactivity timer. If a receive operation has been blocked for this much time without receiving additional data, it returns with a short count or with the error EWOULDBLOCK if no data were received. SO_EVENTMASK defines the bitmask of asynchronous events which are supposed to trigger a notification and can later be retrieved by calling GetSocketEvents. Finally, SO_TYPE and SO_ERROR are options used only with getsockopt(). SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful for servers that inherit sockets on startup. SO_ERROR returns any pending error on the socket and clears the error status. It may be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors. A 0 is returned if the call succeeds, -1 if it fails. The call succeeds unless: [EBADF] The argument s is not a valid descriptor. [ENOPROTOOPT] The option is unknown at the level indicated. INPUTS s - socket level - socket level optname - option name optval - option value optlen - length of option value RESULT ret (D0) - return code bsdsocket.library/inet_addr bsdsocket.library/inet_addr NAME inet_addr -- convert IP address from text to binary form SYNOPSIS ip = inet_addr( cp ); D0 A0 unsigned long inet_addr( char *cp ); FUNCTION The routine inet_addr() interprets character strings representing numbers expressed in the Internet standard `.' notation. It returns numbers suitable for use as Internet addresses. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. INTERNET ADDRESSES Values specified using the `.' notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as ``128.net.host''. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as ``net.host''. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as ``parts'' in a `.' notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). The constant INADDR_NONE is returned by inet_addr() and inet_network() for malformed requests. INPUTS cp - text string RESULT ip (D0) - ip address bsdsocket.library/inet_lnaof bsdsocket.library/inet_lnaof NAME inet_lnaof -- return host part of IP address SYNOPSIS ip = inet_lnaof( in ); D0 stack unsigned long inet_lnaof( struct in_addr in ); FUNCTION This function is identical to Inet_LnaOf(), except that its argument is a structure containing the IP address (instead of accepting the IP address in an unsigned long). Because of that no pragma call for inet_lnaof() exists. This function has been deprecated, because it depends on an obsolete fixed Internet addressing scheme, and does not take subnetting or supernetting into account. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS in - ip address RESULT ip (D0) - host part bsdsocket.library/Inet_LnaOf bsdsocket.library/Inet_LnaOf NAME Inet_LnaOf -- return host part of IP address SYNOPSIS ip = Inet_LnaOf( in ); D0 D0 unsigned long Inet_LnaOf( unsigned long in ); FUNCTION The routine Inet_LnaOf() breaks apart Internet host addresses returning only the local network address part. This function has been deprecated, because it depends on an obsolete fixed Internet addressing scheme, and does not take subnetting or supernetting into account. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS in - ip address RESULT ip (D0) - host part bsdsocket.library/inet_makeaddr bsdsocket.library/inet_makeaddr NAME inet_makeaddr -- create IP address from network number and host number SYNOPSIS ip = inet_makeaddr( net, host ); stack D0 D1 struct in_addr inet_makeaddr( unsigned long net, unsigned long host ); FUNCTION This function is identical to Inet_MakeAddr(), except that its result is returned in a structure, not in an unsigned long. Because of that no pragma call for inet_makeaddr() exists. This function has been deprecated, because it depends on an obsolete fixed Internet addressing scheme, and does not take subnetting or supernetting into account. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS net - network number host - host number RESULT ip (stack) - ip address bsdsocket.library/Inet_MakeAddr bsdsocket.library/Inet_MakeAddr NAME Inet_MakeAddr -- create IP address from network number and host number SYNOPSIS ip = Inet_MakeAddr( net, host ); D0 D0 D1 unsigned long Inet_MakeAddr( unsigned long net, unsigned long host ); FUNCTION This function takes an Internet network number and a local network address and constructs an Internet address from it. This function has been deprecated, because it depends on an obsolete fixed Internet addressing scheme, and does not take subnetting or supernetting into account. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS net - network number host - host number RESULT ip (D0) - ip address bsdsocket.library/inet_netof bsdsocket.library/inet_netof NAME inet_netof -- return network part of IP address SYNOPSIS ip = inet_netof( in ); D0 stack unsigned long inet_netof( struct in_addr in ); FUNCTION This function is identical to Inet_NetOf(), except that its argument is a structure containing the IP address (instead of accepting the IP address in an unsigned long). Because of that no pragma call for inet_netof() exists. This function has been deprecated, because it depends on an obsolete fixed Internet addressing scheme, and does not take subnetting or supernetting into account. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS in - ip address RESULT ip (D0) - network part bsdsocket.library/Inet_NetOf bsdsocket.library/Inet_NetOf NAME Inet_NetOf -- return network part of IP address SYNOPSIS ip = Inet_NetOf( in ); D0 D0 unsigned long Inet_NetOf( unsigned long in ); FUNCTION The routine Inet_NetOf() breaks apart Internet host addresses returning only the network number. This function has been deprecated, because it depends on an obsolete fixed Internet addressing scheme, and does not take subnetting or supernetting into account. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS in - ip address RESULT ip (D0) - network part bsdsocket.library/inet_network bsdsocket.library/inet_network NAME inet_network -- convert network number from text to binary form SYNOPSIS net = inet_network( cp ); D0 A0 unsigned long inet_network( char *cp ); FUNCTION The routine inet_addr() interprets character strings representing numbers expressed in the Internet standard `.' notation. It returns numbers suitable for use as Internet network numbers. This function has been deprecated, because it depends on an obsolete fixed Internet addressing scheme, and does not take subnetting or supernetting into account. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS cp - text string RESULT net (D0) - network number bsdsocket.library/inet_ntoa bsdsocket.library/inet_ntoa NAME inet_ntoa -- convert IP address from binary to text form SYNOPSIS cp = inet_ntoa( ip ); D0 stack char *inet_ntoa( struct in_addr ip ); FUNCTION This function is identical to Inet_NtoA(), except that its argument is a structure containing the IP address (instead of accepting the IP address in an unsigned long). Because of that no pragma call for inet_ntoa() exists. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS ip - ip address RESULT cp (D0) - text string bsdsocket.library/Inet_NtoA bsdsocket.library/Inet_NtoA NAME Inet_NtoA -- convert IP address from binary to text form SYNOPSIS cp = Inet_NtoA( ip ); D0 D0 char *Inet_NtoA( unsigned long ip ); FUNCTION The routine inet_ntoa() takes an Internet address and returns an ASCII string representing the address in `.' notation. For more information on IP addresses and error conditions please see the documentation for inet_addr(). INPUTS ip - ip address RESULT cp (D0) - text string bsdsocket.library/IoctlSocket bsdsocket.library/IoctlSocket NAME IoctlSocket -- control socket parameters SYNOPSIS ret = IoctlSocket( s, req, argp ); D0 D0 D0 A0 long IoctlSocket( long s, unsigned long req, char *argp ); FUNCTION The IoctlSocket() function manipulates the socket parameters of the specified socket. The argument s must be an valid socket descriptor. An ioctl request has encoded in it whether the argument is an ``in'' parameter or ``out'' parameter, and the size of the argument argp in bytes. Macros and defines used in specifying an ioctl request are located in the file <sys/ioctl.h>. The supported requests are: FIOASYNC: The argument is of type (long *). Setting the value to 1 enables asynchronous I/O on the socket. Setting the value to 0 disables asynchronous I/O on the socket. FIOGETOWN, SIOCGPGRP: The argument is of type (struct Task **). The kernel sets the value pointed to to the task that receives notification events for the socket. FIOSETOWN, SIOCSPGRP: The argument is of type (struct Task **). This option defines which task will receive notification events for the socket. FIONBIO: The argument is of type (long *). Setting the value to 1 sets the socket to non-blocking I/O. Setting the value to 0 sets the socket to blocking I/O. FIONREAD: The argument is of type (long *). The kernel sets the value pointed to to the number of readable characters on the socket. SIOCCATMARK: The argument is of type (long *). The kernel sets the value pointed to to 1 if the read pointer for the socket points to a mark in the data stream, and to 0 if the read pointer for the socket does not point to a mark. If an error has occurred, a value of -1 is returned and the return value of Errno() indicates the error. IoctlSocket() will fail if: [EBADF] s is not a valid descriptor. [EINVAL] Request or argp is not valid. INPUTS s - socket descriptor req - request argp - arguments RESULT ret (D0) - return code bsdsocket.library/listen bsdsocket.library/listen NAME listen -- listen for connections on a socket SYNOPSIS ret = listen( s, backlog ); D0 D0 D1 long listen( long s, long backlog ); FUNCTION To accept connections, a socket is first created with socket(), a willingness to accept incoming connections and a queue limit for incoming connections are specified with listen(), and then the connections are accepted with accept(). The listen() call applies only to sockets of type SOCK_STREAM or SOCK_SEQPACKET. The backlog parameter defines the maximum length the queue of pending connections may grow to. If a connection request arrives with the queue full the client may receive an error with an indication of ECONNREFUSED, or, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed. The backlog parameter does not directly specify the maximum length of the backlog queue, but instead specifies an index into a table for the maximum length. Currently the backlog parameter is limited to values from 1 to 5, and the translation table looks as follows: backlog parameter maximum length 1 1 2 3 3 4 4 6 5 variable, default=7 In Miami the maximum length for a backlog parameter of 5 can be changed by the system administrator by modifying the entity 'socket.maxqlen' through MiamiSysCtl. A 0 return value indicates success; -1 indicates an error. listen() will fail if: [EBADF] The argument s is not a valid descriptor. [EOPNOTSUPP] The socket is not of a type that supports the operation listen(). INPUTS s - socket backlog - listen backlog RESULT ret (D0) - return code bsdsocket.library/ObtainSocket bsdsocket.library/ObtainSocket NAME ObtainSocket -- obtain a previously released socket SYNOPSIS s = ObtainSocket( id, domain, type, protocol ); D0 D0 D1 D2 D3 long ObtainSocket( long id, long domain, long type, long protocol ); FUNCTION This function gives a task control over a socket which was previously released to the public socket list by some other task (by calling ReleaseSocket() or ReleaseCopyOfSocket()). The primary use of this function is to pass a socket from InetD to a daemon. "id" is the "key" value returned by ReleaseSocket() or ReleaseCopyOfSocket(). The other parameters can be used to further narrow down the set of sockets. A value of 0 for domain indicates that a socket in any domain is acceptable. The socket number of the socket is returned on success. If an error has occured -1 is returned. INPUTS id - socket id domain - domain type - socket type protocol - protocol RESULT s (D0) - socket bsdsocket.library/recv bsdsocket.library/recv NAME recv -- receive data from a socket SYNOPSIS recvlen = recv( s, buf, len, flags ); D0 D0 A0 D1 D2 long recv( long s, unsigned char *buf, long len, long flags ); FUNCTION The recv() call is normally used only on a connected socket (see connect()) and is identical to recvfrom() with a nil from parameter. As it is redundant, it may not be supported in future releases. recv() returns the length of the message on successful completion. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from (see socket()). If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see IoctlSocket()) in which case the value -1 is returned and the function Errno() returns EAGAIN. The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested; this behavior is affected by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in getsockopt(). The select() call may be used to determine when more data arrive. The flags argument to a recv call is formed by oring one or more of the values: MSG_OOB process out-of-band data MSG_PEEK peek at incoming message MSG_WAITALL wait for full request or error The MSG_OOB flag requests receipt of out-of-band data that would not be received in the normal data stream. Some protocols place expedited data at the head of the normal data queue, and thus this flag cannot be used with such protocols. The MSG_PEEK flag causes the receive operation to return data from the beginning of the receive queue without removing that data from the queue. Thus, a subsequent receive call will return the same data. The MSG_WAITALL flag requests that the operation block until the full request is satisfied. However, the call may still return less data than requested if a signal is caught, an error or disconnect occurs, or the next data to be received is of a different type than that returned. The call returns the number of bytes received, or -1 if an error occurred. The call fails if: [EBADF] The argument s is an invalid descriptor. [ENOTCONN] The socket is associated with a connection-oriented protocol and has not been connected (see connect() and accept()). [EAGAIN] The socket is marked non-blocking, and the receive operation would block, or a receive timeout had been set, and the timeout expired before data were received. [EINTR] The receive was interrupted by delivery of a signal before any data were available. INPUTS s - socket buf - buffer len - length flags - flags RESULT recvlen (D0) - length received bsdsocket.library/recvfrom bsdsocket.library/recvfrom NAME recvfrom -- receive data from a socket SYNOPSIS recvlen = recvfrom( s, buf, len, flags, addr, addrlen ); D0 D0 A0 D1 D2 A1 A2 long recvfrom( long s, unsigned char *buf, long len, long flags, struct sockaddr *addr, long *addrlen ); FUNCTION recvfrom() is used to receive messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented. If from is non-nil, and the socket is not connection-oriented, the source address of the message is filled in. Fromlen is a value-result parameter, initialized to the size of the buffer associated with from, and modified on return to indicate the actual size of the address stored there. For more information please see the description of recv(). INPUTS s - socket buf - buffer len - length flags - flags addr - address addrlen - address length RESULT recvlen (D0) - length received bsdsocket.library/recvmsg bsdsocket.library/recvmsg NAME recvmsg -- receive data from a socket SYNOPSIS recvlen = recvmsg( s, msg, flags ); D0 D0 A0 D1 long recvmsg( long s, struct msghdr *msg, long flags ); FUNCTION recvmsg() is used to receive messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented. The recvmsg() call uses a msghdr structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in <sys/socket.h>: struct msghdr { caddr_t msg_name; /* optional address */ u_int msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter/gather array */ u_int msg_iovlen; /* # elements in msg_iov */ caddr_t msg_control; /* ancillary data, see below */ u_int msg_controllen; /* ancillary data buffer len */ int msg_flags; /* flags on received message */ }; Here msg_name and msg_namelen specify the destination address if the socket is unconnected; msg_name may be given as a null pointer if no names are desired or required. msg_iov and msg_iovlen describe scatter gather locations. msg_control, which has length msg_controllen, points to a buffer for other protocol control related messages or other miscellaneous ancillary data. The messages are of the form: struct cmsghdr { u_int cmsg_len; /* data byte count, including hdr */ int cmsg_level; /* originating protocol */ int cmsg_type; /* protocol-specific type */ /* followed by u_char cmsg_data[]; */ }; The msg_flags field is set on return according to the message received. MSG_EOR indicates end-of-record; the data returned completed a record (generally used with sockets of type SOCK_SEQPACKET). MSG_TRUNC indicates that the trailing portion of a datagram was discarded because the datagram was larger than the buffer supplied. MSG_CTRUNC indicates that some control data were discarded due to lack of space in the buffer for ancillary data. MSG_OOB is returned to indicate that expedited or out-of-band data were received. For more information please see the description of recv(). INPUTS s - socket msg - message header flags - flags RESULT recvlen (D0) - length received bsdsocket.library/ReleaseCopyOfSocket bsdsocket.library/ReleaseCopyOfSocket NAME ReleaseCopyOfSocket -- release a copy of a socket to the public socket pool SYNOPSIS key = ReleaseCopyOfSocket( s, id ); D0 D0 D0 long ReleaseCopyOfSocket( long s, long id ); FUNCTION ReleaseCopyOfSocket() is identical to ReleaseSocket(), except that the socket is first cloned and that the clone is then released to the public socket list, not the original socket, i.e. the original socket remains owned by the caller. Please see the documentation on ReleaseSocket() for more details. INPUTS s - socket id - socket id RESULT key (D0) - key value bsdsocket.library/ReleaseSocket bsdsocket.library/ReleaseSocket NAME ReleaseSocket -- release a socket to the public socket pool SYNOPSIS key = ReleaseSocket( s, id ); D0 D0 D0 long ReleaseSocket( long s, long id ); FUNCTION ReleaseSocket() removes a socket from the task's socket list, and releases it to the public socket list, so another task can grab the socket by calling ObtainSocket(). The id value can be a non-unique number between 0 and 65535 or a unique number higher than 65535. It is also possible to have the kernel pick a unique number by passing UNIQUE_ID as the id. The returned value is the key to be used as the first parameter is ObtainSocket(), or -1 if an error has occured. INPUTS s - socket id - socket id RESULT key (D0) - key value bsdsocket.library/select bsdsocket.library/select NAME select -- synchronous socket I/O multiplexing SYNOPSIS n = select( nfds, readfds, writefds, exceptfds, timeout ); D0 D0 A0 A1 A2 A3 long select( long nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout ); FUNCTION select() examines the socket descriptor sets whose addresses are passed in readfds, writefds, and exceptfds to see if some of their descriptors are ready for reading, are ready for writing, or have an exceptional condition pending, respectively. The first nfds descriptors are checked in each set; i.e., the descriptors from 0 through nfds-1 in the descriptor sets are examined. On return, select() replaces the given descriptor sets with subsets consisting of those descriptors that are ready for the requested operation. Select() returns the total number of ready descriptors in all the sets. The descriptor sets are stored as bit fields in arrays of integers. The following macros are provided for manipulating such descriptor sets: FD_ZERO(&fdsetx) initializes a descriptor set fdset to the null set. FD_SET(fd, &fdset) includes a particular descriptor fd in fdset. FD_CLR(fd, &fdset) removes fd from fdset. FD_ISSET(fd, &fdset) is non-zero if fd is a member of fdset, zero otherwise. The behavior of these macros is undefined if a descriptor value is less than zero or greater than or equal to FD_SETSIZE, which is normally at least equal to the maximum number of descriptors supported by the system. If timeout is a non-nil pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a nil pointer, the select blocks indefinitely. To affect a poll, the timeout argument should be non-nil, pointing to a zero-valued timeval structure. Any of readfds, writefds, and exceptfds may be given as nil pointers if no descriptors are of interest. select() returns the number of ready descriptors that are contained in the descriptor sets, or -1 if an error occurred. If the time limit expires, select() returns 0. If select() returns with an error, the descriptor sets will be unmodified. An error return from select() indicates: [EBADF] One of the descriptor sets specified an invalid descriptor. [EINTR] select() was interrupted, usually by Ctrl-C. [EINVAL] The specified time limit is invalid. One of its components is negative or too large. INPUTS nfds - number of socket descriptors readfds - read fd set writefds - write fd set exceptfds - exception fd set timeout - timeout RESULT n (D0) - numbere of socket descriptors bsdsocket.library/send bsdsocket.library/send NAME send -- send data to a socket SYNOPSIS sendlen = send( s, buf, len, flags ); D0 D0 A0 D1 D2 long send( long s, unsigned char *buf, long len, long flags ); FUNCTION send() is used to transmit data to another socket. send() may be used only when the socket is in a connected state. The length of the message is given by len. If the message is too long to pass atomically through the underlying protocol, the error EMSGSIZE is returned, and the message is not transmitted. No indication of failure to deliver is implicit in a send(). Locally detected errors are indicated by a return value of -1. If no messages space is available at the socket to hold the message to be transmitted, then send() normally blocks, unless the socket has been placed in non-blocking I/O mode. The select() call may be used to determine when it is possible to send more data. The flags parameter may include one or more of the following: #define MSG_OOB 0x1 /* process out-of-band data */ #define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ The flag MSG_OOB is used to send ``out-of-band'' data on sockets that support this notion (e.g. SOCK_STREAM); the underlying protocol must also support ``out-of-band'' data. MSG_DONTROUTE is usually used only by diagnostic or routing programs. See recv() for a description of the msghdr structure. The call returns the number of characters sent, or -1 if an error occurred. send() fails if: [EBADF] An invalid descriptor was specified. [EMSGSIZE] The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. [EAGAIN] The socket is marked non-blocking and the requested operation would block. [ENOBUFS] The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. [ENOBUFS] The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. INPUTS s - socket buf - buffer len - length flags - flags RESULT sendlen (D0) - length sent bsdsocket.library/sendmsg bsdsocket.library/sendmsg NAME sendmsg -- send data to a socket SYNOPSIS sendlen = sendmsg( s, msg, flags ); D0 D0 A0 D1 long sendmsg( long s, struct msghdr *msg, long flags ); FUNCTION sendmsg() is used to transmit data to another socket. For more information please see the description of send(). INPUTS s - socket msg - message header flags - flags RESULT sendlen (D0) - length sent bsdsocket.library/sendto bsdsocket.library/sendto NAME sendto -- send data to a socket SYNOPSIS sendlen = sendto( s, buf, len, flags, to, tolen ); D0 D0 A0 D1 D2 A1 D3 long sendto( long s, unsigned char *buf, long len, long flags, struct sockaddr *to, long tolen ); FUNCTION sendmsg() is used to transmit data to another socket. The address of the target is given by to with tolen specifying its size. For more information please see the description of send(). INPUTS s - socket buf - buffer len - length flags - flags to - address tolen - address length RESULT sendlen (D0) - length sent bsdsocket.library/SetErrnoPtr bsdsocket.library/SetErrnoPtr NAME SetErrnoPtr -- set the pointer to the errno variable SYNOPSIS SetErrnoPtr( errnop, size ); A0 D0 void SetErrnoPtr( void *errnop, long size ); FUNCTION This function was deprecated. Please use SocketBaseTags() with a code of SBTC_ERRNOPTR instead. INPUTS errnop - errno pointer size - size bsdsocket.library/SetSocketSignals bsdsocket.library/SetSocketSignals NAME SetSocketSignals -- set the socket signal mask SYNOPSIS SetSocketSignals( intmask, iomask, urgentmask ); D0 D1 D2 void SetSocketSignals( unsigned long intmask, unsigned long iomask, unsigned long urgentmask ); FUNCTION This function was deprecated. Please use SocketBaseTags() with codes of SBTC_BREAKMASK, SBTC_SIGIOMASK or SBTC_SIGURGMASK instead. INPUTS intmask - interrupt mask iomask - i/o mask urgentmask - urgent mask bsdsocket.library/setsockopt bsdsocket.library/setsockopt NAME setsockopt -- set options on sockets SYNOPSIS ret = setsockopt( s, level, optname, optval, optlen ); D0 D0 D1 D2 A0 d3 long setsockopt( long s, long level, long optname, void *optval, long optlen ); FUNCTION setsockopt() sets the options associated with a socket. Please see the description of getsockopt() for more information. INPUTS s - socket level - socket level optname - option name optval - option value optlen - length of option value RESULT ret (D0) - return code bsdsocket.library/shutdown bsdsocket.library/shutdown NAME shutdown -- shut down part of a full-duplex connection SYNOPSIS ret = shutdown( s, how ); D0 D0 D1 long shutdown( long s, long how ); FUNCTION The shutdown() call causes all or part of a full-duplex connection on the socket associated with s to be shut down. If how is 0, further receives will be disallowed. If how is 1, further sends will be disallowed. If how is 2, further sends and receives will be disallowed. A 0 is returned if the call succeeds, -1 if it fails. The call succeeds unless: [EBADF] S is not a valid descriptor. [ENOTCONN] The specified socket is not connected. INPUTS s - socket how - how RESULT ret (D0) - return code bsdsocket.library/socket bsdsocket.library/socket NAME socket -- create an endpoint for communication SYNOPSIS s = socket( domain, type, protocol ); D0 D0 D1 D2 long socket( long domain, long type, long protocol ); FUNCTION socket() creates an endpoint for communication and returns a descriptor. The domain parameter specifies a communications domain within which communication will take place; this selects the protocol family which should be used. These families are defined in the include file <sys/socket.h>. The currently understood formats are AF_INET (ARPA Internet protocols), The socket has the indicated type, which specifies the semantics of communication. Currently defined types are: SOCK_STREAM SOCK_DGRAM SOCK_RAW SOCK_SEQPACKET SOCK_RDM A SOCK_STREAM type provides sequenced, reliable, two-way connection based byte streams. An out-of-band data transmission mechanism may be supported. A SOCK_DGRAM socket supports datagrams (connectionless, unreliable messages of a fixed (typically small) maximum length). A SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way connection-based data transmission path for datagrams of fixed maximum length; a consumer may be required to read an entire packet with each read system call. This facility is protocol specific, and presently implemented only for PF_NS. SOCK_RAW sockets provide access to internal network protocols and interfaces. The types SOCK_RAW and SOCK_RDM, which is planned, but not yet implemented, are not described here. The protocol specifies a particular protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type within a given protocol family. However, it is possible that many protocols may exist, in which case a particular protocol must be specified in this manner. The protocol number to use is particular to the communication domain in which communication is to take place. Sockets of type SOCK_STREAM are full-duplex byte streams, similar to pipes. A stream socket must be in a connected state before any data may be sent or received on it. A connection to another socket is created with a connect() call. Once connected, data may be transferred using some variant of the send() and recv() calls. When a session has been completed a CloseSocket() may be performed. Out-of-band data may also be transmitted as described in send() and received as described in recv(). The communications protocols used to implement a SOCK_STREAM insure that data is not lost or duplicated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, then the connection is considered broken and calls will indicate an error with -1 returns and with ETIMEDOUT as the specific code in the global variable errno. The protocols optionally keep sockets ``warm'' by forcing transmissions roughly every minute in the absence of other activity. An error is then indicated if no response can be elicited on an otherwise idle connection for a extended period (e.g. 5 minutes). A process is notified if it sends on a broken stream. SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sockets. The only difference is that recv() calls will return only the amount of data requested, and any remaining in the arriving packet will be discarded. SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspondents named in send() calls. Datagrams are generally received with recvfrom(), which returns the next datagram with its return address. An IoctlSocket() call can be used to specify a process group to receive an "urgent" notification when the out-of-band data arrives. It may also enable non-blocking I/O and asynchronous notification of I/O events. The operation of sockets is controlled by socket level options. These options are defined in the file <sys/socket.h>. setsockopt() and getsockopt() are used to set and get options, respectively. A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket. The socket() call fails if: [EPROTONOSUPPORT] The protocol type or the specified protocol is not supported within this domain. [EMFILE] The per-process descriptor table is full. [EACCESS] Permission to create a socket of the specified type and/or protocol is denied. [ENOBUFS] Insufficient buffer space is available. The socket cannot be created until sufficient resources are freed. INPUTS domain - domain type - socket type protocol - protocol RESULT s (D0) - socket bsdsocket.library/SocketBaseTagList bsdsocket.library/SocketBaseTagList NAME SocketBaseTagList -- get/set global parameters SocketBaseTags -- Varargs stub for SocketBaseTagList(). SYNOPSIS ret = SocketBaseTagList( tags ); D0 A0 long SocketBaseTagList( struct TagItem *tags ); ret = SocketBaseTags( tag, ... ); long SocketBaseTags( long tag, ... ); FUNCTION SocketBaseTagList and its varargs equivalent, SocketBaseTags, are used to inspect and change global parameter in the protocol stack. All parameters are passed and retrieved via TagLists. The ti_Tag field determines which parameter to inspect/change, and what to do with it. The ti_Data field contains the value or a pointer to the value. All items passed in the ti_Tag field must have the general form SBTM_...(SBTC_...), where the SBTM_... macro determines the type or access, and the SBTC_... determines the item to be inspected or changed. Possible SBTM_... values include: SBTM_GETREF(SBTC_...): get by reference. The ti_Data field needs to contain a pointer to a memory location where the kernel stores the current value of the selected item. SBTM_GETVAL(SBTC_...): get by value. The kernel stores the current value directly in the ti_Data field. This obviously only works for actual TagLists passed to SocketBaseTagList(), not for TagItems passed to SocketBaseTags() on the stack. SBTM_SETREF(SBTC_...): set by reference. The ti_Data field contains a pointer to the new value of the selected item, which is copied by the kernel. SBTM_SETVAL(SBTC_...): set by value. The ti_Data field contains the new value of the selected item, which is copied by the kernel. Note that some of the items (e.g. SBTC_ERRNOBYTEPTR) already use pointers as parameters. These pointers have nothing to do with the "by reference" argument passing mechanism. If you pass these pointer by reference then ti_Data actually contains a pointer to a pointer. Possible SBTC_... items are: SBTC_BREAKMASK: exec signal mask which corresponds to the EINTR signal (Ctrl-C), typically SIGBREAKF_CTRL_C. SBTC_DTABLESIZE: size of the socket descriptor table. The default is 64. SBTC_ERRNO: The current value of the errno variable. SBTC_ERRNOBYTEPTR, SBTC_ERRNOWORDPTR, SBTC_ERRNOLONGPTR, SBTC_ERRNOPTR(size): Link the program's global errno variable to the protocol stack's internal errno variable, by passing a pointer to the program's variable to the protocol stack. If you use the "library auto-open" feature then this is done automatically for you. SBTC_ERRNOSTRPTR: Get the error string related to an error code. Only SBTM_GET... is allowed. In this special case ti_Data is an input/output parameter: the value passed to SocketBaseTagList() is the error code, and after SocketBaseTagList() has returned it has been replaced with a string pointer to the error string corresponding to the error code. SBTC_FDCALLBACK: Install a callback hook that is called by the kernel whenever the file descriptor table is modified. This function should NOT be used by applications, and is intended for use within low-level link libraries or startup code only. A full description is beyond the scope of this document. Note: this option is deprecated because it does not handle mixed-CPU setups. Use miami.library/MiamiGetFdCallback() and miami.library/MiamiSetFdCallback() in new code instead. SBTC_HERRNO: The current value of the h_errno variable (error code from the resolver). SBTC_HERRNOSTRPTR: Get the error string related to a resolver error code (i.e. an error code in the h_errno variable). Only SBTM_GET... is allowed. In this special case ti_Data is an input/output parameter: the value passed to SocketBaseTagList() is the error code, and after SocketBaseTagList() has returned it has been replaced with a string pointer to the error string corresponding to the error code. SBTC_IOERRNOSTRPTR: Get the error string related to an AmigaOS I/O error code. The use of this code is deprecated. SBTC_LOGFACILITY: Facility code for the syslog mechanism. SBTC_LOGMASK: Filter mask for syslog messages. SBTC_LOGSTAT: Syslog options. SBTC_LOGTAGPTR: Program identification for syslog messages. If you use the "library auto-open" feature then this is set automatically for you. SBTC_S2ERRNOSTRPTR: Get the error string related to a SANA-II error code. The use of this code is deprecated. SBTC_S2WERRNOSTRPTR: Get the error string related to a SANA-II wire error code. The use of this code is deprecated. SBTC_SIGEVENTMASK: Exec signal mask for asynchronous event notification (see GetSocketEvents()). SBTC_SIGIOMASK: Exec signal mask for asynchronous socket events. The use of this mechanism is deprecated. SBTC_SIGURGMASK: Exec signal mask for out-of-band data. The use of this mechanism is deprecated. SocketBaseTagList()/SocketBaseTags() returns 0 on success, or a positive value n, where x is (index minus one) of the TagItem that caused the error. INPUTS tags - taglist RESULT ret (D0) - return code bsdsocket.library/vsyslog bsdsocket.library/vsyslog NAME vsyslog -- create a system log message syslog -- Varargs stub for vsyslog(). SYNOPSIS vsyslog( pri, msg, args ); D0 A0 A1 void vsyslog( long pri, const char *msg, va_list args ); syslog( pri, msg, arg1, ... ); void syslog( long pri, const char *msg, long arg1, ... ); FUNCTION The syslog() function writes message to the system message logger. The message is then written to the system log, in a protocol stack-dependent way. The message is identical to a printf() format string, except that `%m' is replaced by the current error message. (As denoted by the internal variable errno.) A trailing newline is added if none is present. The vsyslog() function is an alternate form in which the arguments have already been captured using the variable-length argument facilities of varargs. The message is tagged with priority. Priorities are encoded as a facility and a level. The facility describes the part of the system generating the message. The level is selected from the following ordered (high to low) list: LOG_EMERG A panic condition. users. LOG_ALERT A condition that should be corrected immediately, such as a corrupted system database. LOG_CRIT Critical conditions, e.g., hard device errors. LOG_ERR Errors. LOG_WARNING Warning messages. LOG_NOTICE Conditions that are not error conditions, but should possibly be handled specially. LOG_INFO Informational messages. LOG_DEBUG Messages that contain information normally of use only when debugging a program. INPUTS pri - priority msg - message args - arguments bsdsocket.library/WaitSelect bsdsocket.library/WaitSelect NAME WaitSelect -- synchronous socket I/O multiplexing SYNOPSIS n = WaitSelect( nfds, readfds, writefds, exceptfds, timeout, D0 D0 A0 A1 A2 A3 signals ); D0 long WaitSelect( long nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout, ULONG *signals ); FUNCTION WaitSelect() is identical to select(), except that it takes an additional parameter: a pointer to an exec signal mask. If the pointer is NULL or points to a an empty mask then WaitSelect() behaves like select(). If the mask pointed to is non-null then WaitSelect() returns if any of these signals has been received. In this case WaitSelect() returns 0, the mask is changed to reflect only those signals that have occured, and the kernel has reset the signals in exec's Task structure. For more information please see the description of select(). INPUTS nfds - number of socket descriptors readfds - read fd set writefds - write fd set exceptfds - exception fd set timeout - timeout signals - signal mask pointer RESULT n (D0) - numbere of socket descriptors